<HTML><HEAD><TITLE>library(minizinc)</TITLE></HEAD><BODY>
[ <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]<H1>library(minizinc)</H1>
Utilities for using MiniZinc with ECLiPSe
<H2>Predicates</H2>
<BLOCKQUOTE>
<DL>
<DT><A HREF="mzn2fzn-4.html"><STRONG>mzn2fzn(+ModelFile, +InstFileOrParMap, ++SolverOrOptions, ?FznFile)</STRONG></A></DT>
<DD>Convert a MiniZinc model into a FlatZinc model</DD>
<DT><A HREF="mzn_load-5.html"><STRONG>mzn_load(++ModelFile, ++SolverOrOptions, ++ParMap, +VarMap, -FznState)</STRONG></A></DT>
<DD>Load a MiniZinc model from a file</DD>
<DT><A HREF="mzn_load_string-5.html"><STRONG>mzn_load_string(++MznModel, ++SolverOrOptions, ++ParMap, +VarMap, -FznState)</STRONG></A></DT>
<DD>Load a MiniZinc model given as a string or list</DD>
<DT><A HREF="mzn_run-2.html"><STRONG>mzn_run(+File, ++SolverOrOptions)</STRONG></A></DT>
<DD>Run a MiniZinc model from a given file</DD>
<DT><A HREF="mzn_run-3.html"><STRONG>mzn_run(+ModelFile, +InstFileOrParMap, ++SolverOrOptions)</STRONG></A></DT>
<DD>Run a MiniZinc model from a given model and instance file</DD>
<DT><A HREF="mzn_run_string-2.html"><STRONG>mzn_run_string(++MznModel, ++SolverOrOptions)</STRONG></A></DT>
<DD>Run a MiniZinc model given as a string or list</DD>
</DL>
</BLOCKQUOTE>
<H2>Reexports</H2>
<BLOCKQUOTE><DL>
<DT><STRONG>reexport struct(_) from <A HREF="../../lib_public/flatzinc/index.html">flatzinc</A></STRONG></DT><DD></DD>
</DL></BLOCKQUOTE>
<H2>Other Exports</H2>
<BLOCKQUOTE><DL>
<DT><STRONG>export macro(of / 2, tr_of / 2, [])</STRONG></DT><DD></DD>
</DL></BLOCKQUOTE>
<H2>Description</H2>

<H3>
Overview
</H3>
<P>
This module allows to run MiniZinc models with ECLiPSe.
MiniZinc models can be either read from a file or stream,
or they can be embedded as strings into ECLiPSe code.
The implementation relies on an external MiniZinc-to-FlatZinc converter,
e.g. mzn2fzn, and on the FlatZinc interpreter lib(flatzinc).
Mappings to different ECLiPSe solvers are possible via the solver
mapping libraries fzn_ic, fzn_fd, fzn_eplex, etc.
</P>

<H3>
Running MiniZinc Models without using this Library
</H3>
<P>
You can run a MiniZinc model by first converting it to FlatZinc yourself,
and then using the lib(flatzinc) library. This can be done either via
an intermediate .fzn file, or by piping the resulting FlatZinc model
into the ECLiPSe-FlatZinc interpreter using e.g.
<PRE>
% mzn2fzn --output-to-stdout model.mzn | eclipse -e "flatzinc:fzn_run(fzn_ic)"
</PRE>
This should work as long as the mzn2fzn command is in your PATH.
Note that mzn2fzn is currently not included with ECLiPSe but comes
with the Melbourne MiniZinc distribution.  You must also make sure that
the specialised globals.mzn file is used, by including e.g. lib/fzn_ic
in mzn2fzn's search path.  For more details see lib(flatzinc).
</P>

<H3>
Running MiniZinc Models using this Library
</H3>
<P>
This library allows you to do everything from within ECLiPSe and let ECLiPSe
invoke the MiniZinc to FlatZinc translator (mzn2fzn) internally with the
correct arguments.  The model can be contained in a file:
<PRE>
?- mzn_run("model.mzn", fzn_ic).
</PRE>
or, if a data instance file is used
<PRE>
?- mzn_run("model.mzn", "instance.dzn", fzn_ic).
</PRE>
Since MiniZinc models are typically small, they can also be embedded as
a string into ECLiPSe code. For example:
<PRE>
    queens8 :-
	mzn_run_string("
		int: n = 8;
		array [1..n] of var 1..n: q;
		constraint
		    forall (i in 1..n, j in i+1..n) (
			q[i]     != q[j]     /\\
			q[i] + i != q[j] + j /\\
			q[i] - i != q[j] - j
		    );
		solve satisfy;
	    ", fzn_ic).
</PRE>
Note that, because of the rules for escaping characters within
ECLiPSe strings, the backslashes had to be doubled!
</P>

<H3>
Installation
</H3>
<P>
This version is intended to to work with Minizinc 0.8 or later!
<P>
In order to be found by lib(minizinc), the Melbourne Minizinc-to-Flatzinc
converter mzn2fzn must be installed in a directory called <CODE>minizinc-&lt;version&gt;</CODE>
in one of the following locations (where we write &lt;ECLIPSEDIR&gt; for
the ECLiPSe installation directory, and &lt;ECLIPSEARCH&gt; for
the name for the machine architecture, e.g. i386_nt for Windows, i386_linux
for Linux):
<OL>
<LI>Directory specified by <CODE>$ECLIPSEMZN</CODE> environment variable</LI>
<LI>The user's home directory, as indicated by $HOME or $HOMEPATH</LI>
<LI><CODE>&lt;location of lib(minizinc)&gt;/&lt;ECLIPSEARCH&gt;</CODE></LI>
<LI><CODE>&lt;ECLIPSEDIR&gt;/lib_public/&lt;ECLIPSEARCH&gt;</CODE></LI>
<LI><CODE>&lt;ECLIPSEDIR&gt;/lib/&lt;ECLIPSEARCH&gt;</CODE></LI>
<LI><CODE>&lt;ECLIPSEDIR&gt;</CODE></LI>
<LI>Parent of <CODE>&lt;ECLIPSEDIR&gt;</CODE> (e.g. "C:/Program Files" on Windows)</LI>
<LI>Directory specified by <CODE>$PROGRAMFILES</CODE> environment variable</LI>
</OL>
<P>
For MiniZinc on Windows, it may be necessary to copy a cygwin1.dll into
the MiniZinc distribution's bin/private folder.


<H3>
Combining a MiniZinc model with Search or I/O in ECLiPSe
</H3>
<P>
There are several reasons why one might want to embed a MiniZinc model
into an ECLiPSe program:
<UL>
<LI>Passing parameters from the ECLiPSe program to the MiniZinc model</LI>
<LI>Getting the model solutions back into ECLiPSe</LI>
<LI>Programming custom search in ECLiPSe</LI>
<LI>Doing custom output beyond what the Zinc output primitive can do</LI>
</UL>
</P><P>
To pass a parameter into a MiniZinc model, a generic MiniZinc model must
be provided, together with a parameter map.
This map is an ECLiPSe list that corresponds to a MiniZinc (actually
FlatZinc) instance file:
<PRE>
queens(N) :-
	mzn_run_string("
		int: n;
		array [1..n] of var 1..n: q;
		constraint
		    forall (i in 1..n, j in i+1..n) (
			q[i]     != q[j]     /\\
			q[i] + i != q[j] + j /\\
			q[i] - i != q[j] - j
		    );
		solve satisfy;
	    ",
	    [n=N],	% parameter map: ZincId=EclipseValue
	    fzn_ic).
</PRE>
Alternatively, the generic model can be kept separately in a MiniZinc file:
<PRE>
queens(N) :-
	mzn_run("n_queens.mzn", [n=N], fzn_ic).
</PRE>
<P>
With the above exmples, search and output are still completely specified
in MiniZinc.
</P><P>
To add your own search routine and/or output, use mzn_load_string/5 or
mzn_load/5. This has the effect of only loading the MiniZinc model
(i.e. setting up the constraints), but then returning to ECLiPSe without
executing any MiniZinc solve or output primitives.  The rest of the work
can then be done in ECLiPSe:
</P>
<PRE>
queens(N, Q) :-
	mzn_load("n_queens.mzn", fzn_ic, [n=N], [q=Q], FznState),
	labeling(Q),
	fzn_output(FznState).
</PRE>
The [q=Q] mapping gives access to the ECLiPSe array Q corresponding to
the MiniZinc array q. This is a normal ECLiPSe array of lib(ic) domain
variables, and can be used for doing search, or outputting the results.
In the example however, we have fallen back onto the FlatZinc output
routine to display the results after search has finished.
</P><P>
Note that even if you do your own search in ECLiPSe, your MiniZinc model
must contain a solve item to be syntactically correct (and to specify
the objective, if any).
</P>

<H3>
Options
</H3>
Instead of just the name of the solver mapping (<CODE>fzn_ic</CODE> in
our examples), a <CODE>zn_options{}</CODE> structure can be given to
customize the behaviour further, e.g.
<PRE>
	mzn_run(File, zn_options{solver:fzn_eplex,var_names:on}.
</PRE>
<DL>
<DT>solver (default: fzn_ic)</DT><DD>
    Determines which ECLiPSe solvers are used.
</DD>
<DT>solutions (default: 1)</DT><DD>
    The maximum number of solutions computed. Only effective if using
    builtin search and not optimizing. (0 = all)
</DD>
<DT>parser (default: fast)</DT><DD>
    Whether to use a 'strict' or 'fast' parser for FlatZinc input.
</DD>
<DT>var_names (default: off)</DT><DD>
    Use lib(var_name) to label ECLiPSe variables with their Zinc names.
    This is useful for debugging.
</DD>
<DT>fzn_tmp (default: file)</DT><DD>
    Use a 'pipe' or intermediate 'file' for FlatZinc.
</DD>
</DL>

<H3>
Mapping between MiniZinc/FlatZinc Data and ECLiPSe Data
</H3>
<P>
When using ECLiPSe with a Mini/FlatZinc model, one needs to be aware of
the mapping from MiniZinc to FlatZinc (e.g. flattening of arrays),
and the representation of FlatZinc data in ECLiPSe.
</P><P>
Note that the ECLiPSe-side representation depends in part on the chosen
solver mapping. The following table shows the mapping used with fzn_ic
(which employs the lib(ic) and lib(ic_sets) solver libraries):
<PRE>
	FlatZinc Type/Syntax		ECLiPSe Type/Syntax
	-----------------------------------------------------------
	string				string
	e.g.	"abc"			"abc"

	bool (false/true)		integer (0/1)
	e.g.	false			0

	int				integer
	e.g.	33			33

	float				float or breal
	e.g.	3.4			3.399__3.401

	set of int			ordered list of integer
	e.g.	{1,5,4}			[1,4,5]
		1..3			[1,2,3]

	array[1..N] of T		structure with functor []/N
	e.g.	[23,54,0]		[](23,54,0)

	var bool			lib(ic) integer variable

	var int				lib(ic) integer variable

	var float			lib(ic) continuous variable

	var set of int			lib(ic_sets) set variable
</PRE>
</P>

<H2>About</H2><UL COMPACT>
<LI><STRONG>Status: </STRONG>prototype
<LI><STRONG>Author: </STRONG>Joachim Schimpf, supported by Cisco Systems and NICTA Victoria
<LI><STRONG>Copyright &copy; </STRONG>Cisco Systems Inc, licensed under CMPL
<LI><STRONG>Date: </STRONG>$Date: 2009/03/28 06:51:05 $
</UL>
<H2>See Also</H2>
<A HREF="../../lib_public/flatzinc/index.html">library(flatzinc)</A>, <A HREF="../../lib_public/fzn_ic/index.html">library(fzn_ic)</A>, <A HREF="../../lib_public/fzn_fd/index.html">library(fzn_fd)</A>, <A HREF="../../lib_public/fzn_eplex/index.html">library(fzn_eplex)</A><HR>Generated from minizinc.eci on 2009-05-27 01:25
</BODY></HTML>
